home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1997 September & October / Amiga-CD 1997 #9-10.iso / aminet / newyork / newyork.doc < prev    next >
Text File  |  1997-06-11  |  17KB  |  359 lines
  1.    **************************************************************************
  2.    ** THIS FILE CONTAINS IMPORTANT INFORMATION. PLEASE READ IT COMPLETELY. **
  3.    **************************************************************************
  4.  
  5.                               NewYork V1 r201 DEMO
  6.  
  7.                        Copyright 1996-1997 Finale Development, Inc.
  8.                          Written by Christopher E. Aldi
  9.  
  10.  
  11.                                     Credits
  12.                                     ~~~~~~~
  13.                      Source Contributions And Support From;
  14.  
  15.           Dan Murrell (danimal) for help with all kinds of neat stuff.
  16.            Osma Ahvenlampi (Tau) for Quote-Printable/Base64 Examples
  17.                 (DarkDesgn) for help with the ActiveList Parser
  18.  
  19.                       ClassAct GUI is Copyright 1995-1997
  20.                                      by the
  21.                            ClassAct Development Team
  22.         Christopher Aldi, Tim Aston, Osma Ahvenlampi and Petter Nilsen.
  23.  
  24.  
  25.                                Installing NewYork
  26.                                ~~~~~~~~~~~~~~~~~~
  27. To  install  NewYork,  just  click on the Install script provided.  You can also
  28. just  run  it  from  the directory.  NewYork does not require any assignments or
  29. external  files  other  than the ClassAct GUI.  The Install script will copy the
  30. required ClassAct GUI to your system if you do not have them already.
  31.  
  32.  
  33.                                Function Overview
  34.                                ~~~~~~~~~~~~~~~~~
  35. First,  it  should  be said that while a number of things and NewYork are fairly
  36. usable  at  this  point in time, not everything has been implemented, enabled or
  37. debuged.   The  overall design is not expected to change much betweeen this beta
  38. release  and final release.  However, suggestions/comments are welcome.  If they
  39. can not be applied to this work in progress, they could be applied to some later
  40. upgraded release and steps taken now to make doing so less painful later.
  41.  
  42. Some noteworthy features include;
  43.  
  44.  o Progressive article retrieval.
  45.  
  46.  o News posting.
  47.  
  48.  o News post reply via News or E-Mail.
  49.  
  50.  o Configurable External E-Mailer (ie. Voodoo, Yam, etc)
  51.  
  52.  o Hierarchical subscription list manager window.
  53.  
  54.  o NNTP User Authorization, the two most common of three forms implemented.
  55.  
  56.  o Fast news header retrieval w/local disk cache option.
  57.  
  58.  o Automatically trims its own data files "on the fly".
  59.  
  60.  o Program "SpeedBar" for easy control of common functions.
  61.  
  62.  o Optional "SpeedTips" popup help system (req. V43 window.class)
  63.  
  64.  o UUDecoder - can be either the currently displayed article, a
  65.    diskfile or a group of selected article(s).
  66.  
  67.  o Font and Screen Mode preferences.
  68.  
  69.  o Optional in-window clock.
  70.  
  71.  o Simple (but growing!) ARexx port.
  72.  
  73.  o Mark articles as read/unread.
  74.  
  75.  o Shows the number of available articles and the number unread.
  76.  
  77.  o Remembers, and optionally filters out, read articles between sessions.
  78.  
  79.  o Articles sorted by Subject, Author, or NNTP Server ID.
  80.  
  81.  o Optional "low-memory" configuration mode for 2M users.
  82.  
  83. A few notes are in order.  The SpeedTips system is something new in ClassAct 2.1
  84. beta which is not available to everyone yet.  However, if your ClassAct is older
  85. you  simply  will  not have this help (simular to bubble help), but NewYork will
  86. continue to function.  News posting/followup is not totally completed yet but it
  87. will post your articles.  Additional note, with ClassAct 2.0 V42.52 window.class
  88. I have enabled the speedtips system via presently undocumented means.  To enable
  89. or disable this help in the main window, press the HELP key.
  90.  
  91. Note  well,  XOVER and XHDR are draft standards, that means not all news servers
  92. will  support  these  new methods of retrieving news.  The final newyork NewYork
  93. will  fall back to RFC977 compliant HEAD or ARTICLE server commands in the event
  94. the XOVER or XHDR system should fail.  
  95.  
  96. The  default  set  up  is for XOVER, however you may select XHDR in preferences.
  97. The  XOVER  system  transfers  (atleast)  8  important  fields  from the article
  98. headers.  NewYork retrieves thus XOVER information in a batch.  About 4 of the 8
  99. fields  are of interest to NewYork at this time.  The XHDR system allows NewYork
  100. to  specify  some  specific  single  field.   This  method can be faster, but is
  101. largely  server  implementation  dependant.   In  the  current NewYork, only the
  102. Subject:   is retrived.  The From:  and Date:  fields are NOT retrieved until an
  103. article  is  selected.   Thus,  XHDR  potentially  uses  less memory than XOVER.
  104. However, XHDR is not as well debugged or complete as the XOVER implementation at
  105. this  time.  In XHDR mode, the article size is Bytes is also unavailable, having
  106. this  information can speed up retrieval of larger articles.  For the time being
  107. the standard/default XOVER method is highly recommended.
  108.  
  109.  
  110.                                   Posting News
  111.                                   ~~~~~~~~~~~~
  112. To  post  a  new  article,  you  must  select  news  composition button from the
  113. speedbar.  The composition/editor window will then open.  The news group to post
  114. the  article too will that of the currently selected news group, i.e., the group
  115. currently  being  read.   You must then type in the subject of your post, unless
  116. you  are  following  up  to the current article, in this case, the subject field
  117. will  automatically  be filled out for you.  You may select a different group to
  118. post  to from a small list by clicking the popup gadget just to the right of the
  119. group  string  gadget.   Cross-posting  by  selecting multiple groups is not yet
  120. supported.   Once  you  have  composed  your  message, you should then click the
  121. post/send  button  in  the  composition  speedbar.   At  any time you may cancel
  122. posting an article by clicking the window's close button.
  123.  
  124. The  article header, body and signature will then be created as a temporary file
  125. in T:  prior to being posted.  Durring the beta period, this file is NOT deleted
  126. after  the  post.   In the case of failure the header content may be valuable in
  127. finding bugs in the article composition/posting system.  It should be also noted
  128. that the signature appended to your article is taken from an optional file named
  129. "PROGDIR:NewYork.Signature".  That is to say, "NewYork.Signature" is loaded from
  130. the programs working directory if found.  This file name and location may become
  131. a user preference in the future.
  132.  
  133.  
  134.                           Preferences & Configuration
  135.                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  136. The first thing you must do is configure newyork, I know, everyone hates this
  137. part, and the beta testers certainly have done & re-done it often. :)
  138.  
  139. In  NewYork  preferences, you will find a click-tab gadget across the top of the
  140. window.   This  organizes  preferences  by  function/catagory.   The  catagories
  141. include; General, Display, Fonts, Program, NetWork, and Encoding.
  142.  
  143. On  the  General  page  you  must  fill in the four (4) string gadgets with your
  144. personal  data,  ie;  your email address, real name, organization (optional) and
  145. your reply (usually the same as your email address).
  146.  
  147. On the Display page you can change the screen mode used by NewYork, be it on the
  148. Workbench, a Custom screen, etc.  You may also adjust the palette of your custom
  149. screen  usingthe  handly  palette  gadget and RGB sliders.  If you intend to run
  150. NewYork  on the workbench, you do not have to change anything, the defaults will
  151. be fine.
  152.  
  153. On  the  Fonts  page  you  may  adjust  the  fonts used in various places within
  154. NewYork.   You  may select the interface font (the font that is used for the GUI
  155. when  on  a  custom screen), the message font (the font used to display the news
  156. article)  and  the  index  font  (the font used to display the group and article
  157. listviews).   NewYork  should  function  normally with the default settings, but
  158. feel free to experiment with different font settings.
  159.  
  160. On  the  Program  page you may set various program related settings.  Here again
  161. NewYork  will  function  with  the  defaults,  however,  you will likely want to
  162. configure   the  path  and  arguments  for  your  email  program.   The  default
  163. configuration  is  set  up to use the "Voodoo" email client.  You need only edit
  164. the  path  to  the  executable program.  For other emailers, consult your mailer
  165. documentation for use as a plug-in via command line arguments.  In addition you
  166. may wish to enable the 'Cache Headers' option.  Enabling this will cause NewYork
  167. to  save  (cache)  header data (ie; Subject:, From:, Date:, etc) to a small disk
  168. data  file.   When revisiting a news group, this cache is reloaded and only news
  169. article  headers  not present in the cache are downloaded from the server.  This
  170. makes NewYork *MUCH* faster to use, especially notiable on large & highly active
  171. groups.
  172.  
  173. On  the  NetWork  page you must set your NNTP news server address.  As a rule of
  174. thumb, if you email address is 'moocow@grassfarm.net' then your news server will
  175. likely  be  called  'news.grassfarm.net'.   NewYork tries to figure out the news
  176. server  name  if  it can, but you should confirm this information which your ISP
  177. should  have  made available to you.  The default "port" for news is 119, unless
  178. your  ISP  directed  you  to use something else, you should except this standard
  179. default  setting.   Some  ISP  news servers require authorizations to do certain
  180. functions  such  as  posting news, or downloading the servers active group list.
  181. NewYork  supports two of the three known standards.  If your ISP requires a news
  182. server login name and password, this is the authorization information, it may or
  183. may not be the same as your ISP user login and password.
  184.  
  185.  
  186.                               Subscription Editor
  187.                               ~~~~~~~~~~~~~~~~~~~
  188. The  next  thing  you will want to do with NewYork is download the group active
  189. list  from  the  news  server.  Most news servers carry atleast 15,000 to 35,000
  190. groups.   Thus, the active file is generally 500K to possibly over 1M, depending
  191. on  the speed of your network connection, this could take several minutes.  Once
  192. you  have  the list, NewYork will parse the active list to its own custom sorted
  193. hierarchical subscription resource format. This format is significantly smaller
  194. than the format received from the server, yielding a data file approximatly 150K
  195. to 300K.
  196.  
  197. Such  a  large  list  can  be  difficult  to manage, in both user interface, and
  198. programmatically  sorting  and/or  processing such data .  NewYork presents this
  199. large  list  as a hierarchical group tree list.  For example, rather than a list
  200. of groups like so;
  201.  
  202. --------------------------------
  203. comp.sys.amiga.advocacy
  204. comp.sys.amiga.announce
  205. comp.sys.amiga.programmer
  206. comp.sys.atari.advocacy
  207. comp.sys.atari.programmer
  208. --------------------------------
  209.  
  210. NewYork visually organizes the groups in a tree like so;
  211.  
  212. --------------------------------
  213. + comp
  214.    + sys
  215.        + amiga
  216.              advocacy
  217.              announce
  218.              programmer
  219.        + atari
  220.              advocacy
  221.              programmer
  222. --------------------------------
  223.  
  224. This may or may not confuse some of you, however once you try to use it it will
  225. quickly make sence.  Such listtrees are fairly common place in Windows, Mac, MUI
  226. and other interfaces.  The hierarchical tree makes handling a large list such as
  227. this much more managable because you can expand/colapse the group hierarchy to
  228. show or hide various groups.  For example you could colapse the list at the
  229. 'amiga' level like so;
  230.  
  231. --------------------------------
  232. + comp
  233.    + sys
  234.        - amiga
  235.        + atari
  236.              advocacy
  237.              programmer
  238. --------------------------------
  239.  
  240. By  default,  all  levels are colapsed yielding a short manageable list, you can
  241. then  move  to  an  appropriate section, such as alt or comp.  Expand the level,
  242. such  as  alt,  to reveal sub-catatories of binaries, source, etc.  And continue
  243. down in to the group tree.
  244.  
  245. The  deepest/last  level  of  the  tree are actual groups, these have checkboxes
  246. beside  the  group  names.  Selecting the check box subscribes you to the group,
  247. like  wise an unchecking a checkbox unsubscribes you from that group.  The state
  248. of  these checkboxes are stored directly in newyork's custom resource data file.
  249.  
  250. Memory  usage  for  the  subscription editor is keep fairly low compared to most
  251. other  modern  news  readers,  however,  it  can still requier as much as 2 to 4
  252. megabytes  of  memory  to build the list.  I have been unable to confirm it, but
  253. I've  been  told  mNews  can  use  as much as 8 megs, and perhaps more for large
  254. lists.   If you don't have the memory to spare, you can join a group "on demand"
  255. by  selecting  the  "Join  By Name" option from the project menu.  Here, you can
  256. simply type in the name of the group into the string gadget.  This will retrieve
  257. the   groups  article  list  immediatly.   Use  of  this  feature  is  presently
  258. discouraged  due to some remaining odd bug(s) - but it doesn't hurt to give it a
  259. try and cross your fingers! ;)
  260.  
  261.                                 KeyBoard Control
  262.                                 ~~~~~~~~~~~~~~~~
  263. A great deal of NewYork can be controlled via the keyboard.
  264.  
  265. The main window article text display can be controlled as so;
  266.  
  267.     Space = Page down
  268.     BkSpc = Page up
  269. Cursor Up = Up 1 line
  270. Cursor Dn = Down 1 line
  271.  
  272.         N = Read next article
  273.         P = Read previous article
  274.  
  275. The main window group and article lists can be controlled as so;
  276.  
  277.         7 = Top of list
  278.         1 = Bottom of list
  279.         8 = Up 1 line
  280.         2 = Down 1 line
  281.         9 = Page up
  282.         3 = Page down
  283.     Enter = Retrieve selected group, or article.
  284.  
  285. The subscription window list functions in a simular fashion.
  286.  
  287.  
  288.                                      To Do
  289.                                      ~~~~~
  290.  
  291. I  would  like  to  complete  the  following list of features for the future of
  292. NewYork.   Any other simple or useable feature suggestions are welcome.  However
  293. the  focus  now is to complete/polish the loose ends, freeze the feature set and
  294. focus on debugging any remaining bugs for release ASAP.
  295.  
  296.  o Automatically ask user to download news group active list from
  297.    server upon initial configuration.
  298.  
  299.  o News post file attachment.
  300.  
  301.  o MIME Base64 Encoding/Decoding.
  302.  
  303.  o More (useful) ARexx commands.
  304.  
  305.  o KillFile Editor (Scoring Perhaps?)
  306.  
  307.  o Replace use of textfield.gadget for article display with a more
  308.    efficient and customizable text display engine.
  309.  
  310.  
  311.                                      Thanks
  312.                                      ~~~~~~
  313. Far  from  a  complete list of those who have had a taste of NewYork and offered
  314. input  durring  development,  but  I'd  like to thank some of my most vocal beta
  315. testers for a job well done:
  316.  
  317.  Rafael Munoz (Zonum) <zonum@shadow.net>
  318.  (Sibbi) <>
  319.  (frotz) <Frotz@op.net>
  320.  Greg Scott (NAN) <gscott@interramp.com>
  321.  Dan Murrell, Jr (danimal) <djm2@ra.msstate.edu>
  322.  Magnus Lilja (lilja) <lilja@lysator.liu.se>
  323.  Timothy J. Aston (Timmer)  <timmer@warped.com>
  324.  Mike Latinovich (SkyGuy) <mlatin@owens.ridgecrest.ca.us>
  325.  Scott Ellis (ScottE) <sellis@rohan.sdsu.edu>
  326.  Mark Beal (Bealy) <mbeal@thenet.co.uk>
  327.  Eric Webb (Foobar) <>
  328.  (TheBarron) <>
  329.  (NightSpd) <>
  330.  (NiteFlite) <>
  331.  Eric (RMerlin) <>
  332.  
  333.                                   Legal Notes
  334.                                   ~~~~~~~~~~~
  335. NewYork is Copyright 1996-1997 by Christopher E. Aldi, of Finale Development, Inc.
  336.  
  337. The  included BOOPSI gadget and image classes are part of ClassAct, Published by
  338. Finale Development, Inc.   For  information  about  using ClassAct in your own
  339. applications, drop by the web page at;
  340.  
  341. http://thule.icenet.no/classact
  342. http://www.warped.com/~timmer/classact
  343.  
  344. Or you may also contact me, Christopher Aldi via email; caldi@finale-dev.com
  345.  
  346.  
  347.                                    BugReports
  348.                                    ~~~~~~~~~~
  349. Please report any bugs, suggestions or quirks to me and I will try to address
  350. them as soon as possible.  A number of people have been testing NewYork for
  351. some time now, and it has proven itself reasonably stable, however, nothing
  352. or no one is perfect, especially a beta.  Getting detailed bug reports from
  353. users most helpful in this stage of development.  When reporting bugs it is
  354. most helpful to know the revision of newyork, any system hacks or patches
  355. being used, the last few things you did with NewYork before the crash or error,
  356. and if at all possible, any 'enforcer' output. Enforcer is a debuging tool
  357. that requires an MMU, it should be available on AmiNet.
  358.  
  359.